Why

Refs LE-2382

Opening or saving a flow moves the whole graph uncompressed, three times per edit cycle: once on open, once on the save, and once more on the echo the server sends back. Across the 27 starter projects that payload is 4,657 KB — and 92.2% of it is node templates, 68.5% of the total being component Python source the browser received from us and sends straight back, unchanged.

The helper that would have solved half of this already exists and is in production on the flow list and the component types endpoint — it was simply never applied to reading or saving a single flow. It also compresses unconditionally, without reading Accept-Encoding, so on seven routes a client that cannot decompress receives a binary body it never asked for.

This compresses the two downward legs of that cycle. It touches transport only — nothing about how a flow is stored, saved, merged or overwritten changes.

Version history has the same shape at rest, and compressing it is the other half of this ticket. It is deliberately not here: it touches flow_version, where the multi-user editing work (#14903) is landing, and its migration would branch from the same Alembic head that work will use. It follows as its own PR under this ticket once that settles.

What

• On the wire. Starlette's GZipMiddleware, registered once for the whole API at level 6 with a 1,000-byte floor. It is registered innermost, before ContentSizeLimitMiddleware: the BaseHTTPMiddleware layers above it turn every response into a stream, and a streamed response carries no Content-Length for minimum_size to test — a gzip registered outside them compresses 200-byte replies too. Binary content types are excluded through the library's own list plus the ones it does not cover and this app serves: application/octet-stream, application/pdf and the three OOXML types. docx, xlsx and pptx are ZIP containers and PDF carries compressed streams — measured on a synthetic docx, 126 KB in and 126 KB out, 0.0% gain; downloads are capped at max_file_size_upload (1024 MB by default), which extrapolates to roughly 17 seconds of CPU for nothing. Streaming is a deliberate decision, not a side effect: text/event-stream is excluded by the library, but the canvas build stream is application/x-ndjson (api/build.py:446) and is compressed. Streamed responses also bypass minimum_size entirely — gzip.py consults the floor only when more_body is false — so this applies to every build event stream regardless of size.
• The unconditional helper is gone. compress_response and its seven call sites are removed, so those routes now honour Accept-Encoding like the rest of the API. They keep bypassing response_model validation through JSONResponse, exactly as before.
• Dependency. starlette>=1.5.0, declared directly because the middleware is now used here rather than only through FastAPI. exclude_content_types and the worker-thread offload for large bodies both arrived in 1.5, and the offload is what makes level 6 safe on the event loop. fastapi 0.139.2 requires only starlette>=0.46.0, so nothing capped the bump; locked with --upgrade-package starlette so no other dependency moved.

Measured

Same machine, before and after: the backend was started on release-1.13.0 without the change, the largest starter project was created as a flow with three versions, and every probe was taken; then the same scenario on this branch. A corpus control ran on both sides — identical files, identical gzip — and reproduced 12 of its 14 metrics exactly, with timings inside ±2.96%, which is what says the ruler did not move between the two readings.

The second row is the point of the change as much as the first: a client that does not advertise gzip gets exactly the bytes it got before.

The upload leg stays uncompressed here, which is why the cycle improves by half rather than by three quarters. That leg needs new plumbing on both sides and is left as a follow-up.

Compression level was picked by measurement, not by the library default. Twenty-seven flows, minimum of seven runs, Python 3.12:

level   corpus      reduction   ms/flow   ms on largest
  1     1,332 KB      71.4%      1.04         2.02      ███████████████
  4     1,133 KB      75.7%      1.76         3.46      ██████████████████
  6     1,070 KB      77.0%      3.38         6.75      ███████████████████   <- chosen
  9     1,063 KB      77.2%      7.79        15.99      ███████████████████

Level 9 — what GZipMiddleware uses when you pass nothing — buys 0.1 points over level 6 for 2.3× the CPU. Level 6 is passed explicitly.

Build event streams

Measured per chunk with Z_SYNC_FLUSH, exactly as the middleware compresses them:

Delivery stays incremental — Z_SYNC_FLUSH emits each chunk as it is produced — so the only regression is a stream that carries a single tiny event and closes, which a build never does. Compression is kept on ndjson deliberately, and three tests pin it.

This leaves an asymmetry worth naming: the build path (x-ndjson) is compressed while the chat and run streams (text/event-stream) are not, because the library excludes the latter. Both stay incremental, so this is the library's conservatism rather than a requirement of ours. Unifying them is a separate decision and is not taken here.

Not in scope

• Delta saves. The flow is a single JSON column, so the server would still read, modify and write the whole document. The real win needs the graph normalized into tables.
• Dropping unchanged component source from the save payload. It requires the server to know the client's copy was based on the same version of the flow, and no such check exists yet.
• The autosave interval. Every save is a full-graph overwrite, so that interval is the window in which two people diverge — it belongs with the multi-user editing work, not here.
• Delta-chained version history. Every retention path in this codebase prunes by count over self-contained rows; a chain makes the base undeletable until the next version is rebuilt from it, over a prune that already keeps deployed versions in the middle of the queue.

How to validate

1. S1 — curl -s -D- -o /dev/null -H 'Accept-Encoding: gzip' -H "x-api-key: $KEY" localhost:7860/api/v1/flows/$FLOW_ID. Expected: content-encoding: gzip and vary: Accept-Encoding in the headers.
2. S2 — The same request with -H 'Accept-Encoding: identity'. Expected: no content-encoding header, a readable JSON body, and the same byte count as before this change.
3. S3 — Edit a flow on the canvas with devtools open. Expected: the PATCH /api/v1/flows/{id} response carries content-encoding: gzip.
4. S4 — curl -s -D- -o /dev/null -H 'Accept-Encoding: gzip' localhost:7860/api/v1/version. Expected: no content-encoding — the body is under the 1,000-byte floor.
5. S5 — Download a file through the files API with Accept-Encoding: gzip. Expected: no content-encoding.
6. Browser console and server log with no new error.

Tests

New: src/backend/tests/unit/api/test_response_compression.py (18 tests — asks, does not ask, echo, below threshold, plus a response served under each excluded content type proving it comes back uncompressed, with a compressible type on the same app as the control; a streamed ndjson response asserting it is compressed, a single-event stream asserting the size floor does not apply to streams, an excluded type staying uncompressed while streamed, and the registration order the design rests on — verified to fail when the order inverts).

Removed: src/backend/tests/unit/utils/test_compression.py, along with the helper it covered.

Passing unchanged: test_flows.py (95), test_flow_version.py (56), and test_endpoints.py + test_deployment_sync.py + test_projects.py (215 together).

Note

Compression is decided once, for the whole API, and cannot be turned off without editing the source: there is no setting for the level or the floor. That is deliberate — the values come from the measurement above and an operator has no information we do not have — but it is a constraint worth naming.

The storage half of this ticket is measured and ready on perf/LE-2382-version-history-at-rest: gzipping flow_version.data took a real table from 1.00 MB to 0.22 MB on SQLite. It is held back for the reason given above, not for lack of evidence.